\documentclass[titlepage]{article}
\usepackage[english]{babel}
\selectlanguage{english}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{graphicx}
\usepackage{floatflt}
\usepackage{hyperref}
\usepackage{listings}

\def\pdfBorderAttrs{/Border [0 0 0] } % No border arround Links
\hypersetup{
	pdfauthor={Kai "Cleeus[JgKdo]" Dietrich},
	pdftitle={iW2P - A WebService},
	pdfsubject={Specification and documentation for the iW2P webservice},
	pdfkeywords={iW2P, XML-RPC, INFiltration},
  colorlinks,
  pdfstartpage=1,
  bookmarksnumbered=true,
  plainpages=false,
  linkcolor=black,
  citecolor=black,
  urlcolor=black
 }

\begin{document}
\lstset{language=PHP}

\title{\begin{huge}iW2P\end{huge}\\Specification and Documentation}
\author{Kai Dietrich}
\date{\today}
\maketitle

\null
\vfill
\thispagestyle{empty}
\bigskip
\begin{quote}
    Copyright \copyright{}  Kai Dietrich.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled ``GNU
    Free Documentation License''.
\end{quote}
\bigskip
\clearpage

\thispagestyle{empty}
\tableofcontents
\clearpage

\section{Libraries}
	The iW2P reference server is written in PHP and uses the The Incutio XML-RPC Library.
	You can finde the Incutio XML-RPC documentation here:
	
	\noindent\url{http://scripts.incutio.com/xmlrpc/}
	
\section{XML-RPC Server Communication}
	XML-RPC is an easy to use specification for remote function calls over HTTP.
	A client which wants to use a server function, sends a specialy crafted, XML formated,
	HTTP POST Request to the Server which replies with an XML formated response with the
	result of the remote procedure call.
	
	For more documentation see www.xmlrpc.com, they have a short spec for XML-RPC.
	\subsection{iW2P Extensions}
		The biggest advantage of XML-RPC - it's simplicity - is, at the same moment,
		it's biggest disadvantage. The iW2P reference server uses a few non-standard
		extensions to improve usability and efficiency of the system.
		
		\subsubsection{Introspection}
			The iW2P reference server supports a set of reserved functions which provide
			an insight into the interface of the server. This feature is called introspection.
			A documentation of these functions can be found here:
			
			\noindent\url{http://scripts.incutio.com/xmlrpc/introspection.html}
			
			\noindent In short, you have the following methods:
\begin{verbatim}
system.listMethods
system.methodSignature
system.methodHelp
\end{verbatim}
			
			\noindent The Response of the server to \verb system.listMethods looks like this (iW2P v0.01):
			
\begin{verbatim}
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<array><data>
<value><string>INFLobby.pollKeepAlive</string></value>
<value><string>INFLobby.pollUpdates</string></value>
<value><string>INFLobby.setStatus</string></value>
<value><string>INFLobby.setQueues</string></value>
<value><string>INFLobby.getQueues</string></value>
<value><string>INFLobby.setNickname</string></value>
<value><string>INFLobby.getSessionId</string></value>
<value><string>INFLobby.getChallenge</string></value>
<value><string>INFLobby.getPollTimings</string></value>
<value><string>system.methodHelp</string></value>
<value><string>system.methodSignature</string></value>
<value><string>system.multicall</string></value>
<value><string>system.listMethods</string></value>
<value><string>system.getCapabilities</string></value>
</data></array>
</value>
</param>
</params>
</methodResponse>
\end{verbatim}
			
			Take a look at the output of \verb iW2P/server/debug/xmlrpcclient.php - it will show you
			the result of all introspection calls before continueing with calls to the INFLobby Interface.
			
		\subsubsection{GZ-Compression}
			To reduce latency and traffic the iW2P server supports GZ/deflate compression via PHPs
			output buffer ( \verb ob_start('ob_gzhandler'); ).
			Compression is part of the HTTP protocoll, so most XML-RPC libraries should be able
			to handle this.
			To request a compressed reply, your HTTP request has to waer the
			\begin{verbatim}Accept-Encoding: gzip\end{verbatim} flag in it's header.

\section{The INFLobby XML-RPC Interface}
		As seen above, the INFLobby interface provides the following set of functions:
\begin{verbatim}
polltimings INFLobby.getPollTimings();
challenge INFLobby.getChallenge();
int INFLobby.getSessionId(int captchaid, string answer);
boolean INFLobby.setNickname(int sessionid, string nickname);
queueinfo[] INFLobby.getQueues(int sessionid);
boolean INFLobby.setQueues(int sessionid, int[] queues);
boolean INFLobby.setStatus(int sessionid, int status);
pollinfo INFLobby.pollUpdates(int sessionid);
boolean INFLobby.pollKeepAlive(int sessionid);
\end{verbatim}
		You can find a complete function reference in \ref{sec:InterfaceReferences}.
		
		
	\subsection{Design Concepts}
		iW2P uses the following concepts during operation.
		
		\subsubsection{General working}
			To use the iW2P service the client has to login to the server.
			After beeing logged in, it can check the servers settings, set it's
			own options and preferences and check the waiting queues.
			
		\subsubsection{Queues, Users and Servers}
			iW2P keeps track of users. Each user has a sessionid, a userid and a status.
			Also, iW2P has queues. Each queue is associated with a server which a player can join.
			The status of a user indicates if he is waiting (status=0) or playing (status=queueid).
			
		\subsubsection{CAPTCHA Login}
			Without beeing logged in to the iW2P service, you can use exactly three functions:
			\begin{description}
				\item[INFLobby.getPollTimings] tells you what poll frequencies the server
					expects from you.
				\item[INFLobby.getChallenge] returns you a captchaid and a base64
					encoded JPEG file (other challenges possible for the future).
				\item[INFLobby.getSessionId] checks if the captcha answer is correct and
					supplies you with a sessionid for further operations. This is the login function.
			\end{description}
			
			As said, the reply of \verb INFLobby.getChallenge contains a captcha and an ID for the
			captcha. To procede in the login process, you have to solve the captcha and return
			the answer to the server via
			\begin{verbatim}int INFLobby.getSessionId(int captchaid, string answer);\end{verbatim}
			
		\subsubsection{Authentication}
			After you have successfully solved the captcha you get a sessionid.
			This sessionid has to be supplied with every other function call to
			authenticate you as a user. If you time out, your session id becomes
			invalid and you have to login again.
			
		\subsubsection{Polling}
			Due to the WebBased XML-RPC design, iW2P has to rely on polling
			to track it's clients. Generally polling is a bad solution, but
			in this case it has to be used.
			
			Clients have to poll the server to keep their sessions alive.
			There are two polling functions:
\begin{verbatim}
boolean INFLobby.pollKeepAlive(int sessionid);
pollinfo INFLobby.pollUpdates(int sessionid);
\end{verbatim}
			\verb INFLobby.pollKeepAlive does exactly what it says, it keeps the
			session alive, nothing else. Thus traffic is minimal.
			\verb INFLobby.pollUpdates also updates the internal session timestamp
			and keeps your session alive, but it returns a whole bunch of
			information about the users in the waiting queues. Thus, it produces
			quiet some traffic.
			
			To further reduce the needed polling traffic, exspecially during gameplay,
			there are two polling frequencies, which depend on your current status.
			First, there is the \verb waiting frequency, which your client has to reach
			when the player is in the waiting status, thus not playing on a server.
			Second, there is the \verb playing frequency which should be somewhat lower.
			Both frequencies can be configured via the server settings.
			
	\subsection{A Short How-To}
		This is a pseudocode example (with PHP-style arrays/structs)
		for an iW2P application:

\begin{verbatim}
function main() {
  //first get the polltimings from the server
  polltimings = INFLobby.getPollTimings();
  
  //request a challenge
  challenge = INFLobby.getChallenge();
  
  //let the user solve the challenge
  answer = GUI->getCaptchaAnswer(challenge['content']);
  
  //request a sessionid for the challenge answer
  sessionid = INFLobby.getSessionId(challenge['captchaid'], answer);
  
  //tell the server the players nickname
  INFLobby.setNickname(sessionid, "INF_Player");
  
  //get the queues which are available on the iW2P server
  queueinfo = INFLobby.getQueues(sessionid);
  
  //njjjj, do some stupid pseudo gui stuff with the queues
  //(aka, create widgets and so on)
  GUI->displayQueues(queues);
  
  //poll the server until application is closed
  while(true) {
    //if the user is idling, poll with a higher frequency and get updates
    if(user->status = 0) { //waiting
      updates = INFLobby.pollUpdates(sessionid);
      GUI->displayUpdates(updates);
      sleep(polltimings['waiting']*0.75);
    } else { //playing, poll with a lower frequency and just keep the session alive
      INFLobby.pollKeepAlive(sessionid);
      sleep(polltimings['playing']*0.75);
    }
  }
}

//join into some queues
function GUICallback_joinQueues(int queues[]) {
  INFLobby.setQueues(queues);
}

//set own status to either 0 (waiting) or !0 (playing)
function GUICallback_setStatus(int status) {
  INFLobby.setStatus(status);
}
\end{verbatim}
	
	\subsection{Interface Reference}
	\label{sec:InterfaceReferences}
	
\subsubsection{INFLobby.getPollTimings}
description: returns the poll timing settings of the server\\
parameters:\\			
request:
\begin{verbatim}
<methodName>INFLobby.getPollTimings</methodName>
<params></params>
\end{verbatim}
response:
\begin{verbatim}
<struct>
<member><name>waiting</name><value><int>60</int></value></member>
<member><name>playing</name><value><int>600</int></value></member>
</struct>
\end{verbatim}
\begin{description}
	\item[waiting] maximum time in seconds between two poll operations during waiting state
	\item[playing] maximum time in seconds between two poll operations during playing state
\end{description}

			
			
		
\subsubsection{INFLobby.getChallenge}
desciption: returns a captcha challenge\\
parameters:\\
request:
\begin{verbatim}
<methodName>INFLobby.getChallenge</methodName>
<params></params>
\end{verbatim}
response:
\begin{verbatim}
<struct>
<member><name>challengeid</name><value><int>390</int></value></member>
<member><name>mimetype</name><value><string>image/jpeg</string></value></member>
<member>
  <name>content</name>
  <value><base64>the base64 encoded file</base64></value>
</member>
</struct>
\end{verbatim}

\begin{description}
	\item[challengid] the id of the returned challenge
	\item[mimetype] the mime-type of the content
	\item[content] a base64 encoded file, usually a jpeg file
\end{description}


	
\subsubsection{INFLobby.getSessionId}
description: checks if the given answer and the given captcha match and returns a sessionid\\
parameters: \verb"int captchaid, string answer"
\begin{description}
	\item[captchaid] the id of the captcha
	\item[answer] the answer to the captcha
\end{description}
request:
\begin{verbatim}
<methodName>INFLobby.getSessionId</methodName>
<params>
<param><value><int>390</int></value></param>
<param><value><string>ABCD</string></value></param>
</params>
\end{verbatim}
response:
\begin{verbatim}
<int>2122907659</int>
\end{verbatim}
returns 0 if the answer was wrong



\subsubsection{INFLobby.setNickname}
description: set the users nickname\\
parameters: \verb"int sessionid, string nickname"
\begin{description}
	\item[sessionid] the users sessionid
	\item[nickname] the users nickname
\end{description}
request:
\begin{verbatim}
<methodName>INFLobby.setNickname</methodName>
<params>
<param><value><int>2122907659</int></value></param>
<param><value><string>INF_Player</string></value></param>
</params>
\end{verbatim}
response:
\begin{verbatim}
<boolean>1</boolean>
\end{verbatim}
1 on success, 0 on failure



\subsubsection{INFLobby.getQueues}
description: returns all information about the queues which are available on the server\\
parameters: \verb"int sessionid"\\
\begin{description}
	\item[sessionid] the users sessionid
\end{description}
request:
\begin{verbatim}
<methodName>INFLobby.getQueues</methodName>
<params>
<param><value><int>2122907659</int></value></param>
</params>
\end{verbatim}
response:
\begin{verbatim}
<array><data>
<value>
  <struct>
    <member><name>title</name><value><string>ServerName</string></value></member>
    <member><name>ip</name><value><string>192.168.0.1</string></value></member>
    <member><name>port</name><value><string>7777</string></value></member>
    <member><name>description</name>
      <value><string>description text</string></value>
    </member>
    <member><name>queueid</name><value><int>1</int></value></member>
    <member><name>count</name><value><int>0</int></value></member>
  </struct>
</value>
...
</data></array>
\end{verbatim}
\begin{description}
	\item[title] the server name
	\item[ip] the IPv4 address of the server
	\item[port] the port of the server
	\item[description] a description text for the server
	\item[queueid] unique id for the queue
	\item[count] number of users currently waiting in the queue
\end{description}
Returns an array with 0 elements, if sessionid was invalid.

\subsubsection{INFLobby.setStatus}
\label{sec:INFLobby.setStatus}
description: sets the players status or logs the user out\\
parameters: \verb"int sessionid, int status"
\begin{description}
	\item[sessionid] the users sessionid
	\item[status] the users status\\
		status=0 means, the user is waiting\\
		status>0 means, the user is playing on the queue with queueid=status\\
		status<0 means, the user logs out\\
\end{description}
request:
\begin{verbatim}
<methodName>INFLobby.setStatus</methodName>
<params>
<param><value><int>2122907659</int></value></param>
<param><value><int>1</int></value></param>
</params>
\end{verbatim}
response:
\begin{verbatim}
<boolean>1</boolean>
\end{verbatim}
1 on success, 0 on failure
	

	
\subsubsection{INFLobby.pollUpdates}
description: keep session alive and get the current state of the waiting queues\\
parameters: \verb"int sessionid"
\begin{description}
	\item[sessionid] the users sessionid
\end{description}
request:
\begin{verbatim}
<methodName>INFLobby.pollUpdates</methodName>
<params>
<param><value><int>2122907659</int></value></param>
</params>
\end{verbatim}
response:
\begin{verbatim}
<struct>
  <member><name>queues</name><value>
  	<struct>
			<member><name>3</name>
			<value><array><data>
				<value><int>216</int></value>
				... (more userids)
			</data></array></value>
			</member>
			... (on member for each queueid)
			
  <member><name>users</name>
    <value>
      <array><data>
        <value>
          <struct>
            <member><name>userid</name><value><int>216</int></value></member>
            <member><name>nick</name><value><string>INF_Player</string></value></member>
            <member><name>status</name><value><int>0</int></value></member>
          </struct>
        </value>
        ...
      </data></array>
    </value>
  </member>
</struct>
\end{verbatim}
Returns \verb"<boolean>0</boolean>" on failure.

This response is more complicated. It consists of a struct which has two members:
\verb"queues" and \verb"users". \verb"queues" contains lists of userids.
\verb"users" contains a list of all userids which are logged on to the server
and associated information about the user. \verb"queues" only contains the userids
which are waiting on the queues. So there can be users who are on the \verb"users"
list but aren't on any waiting queue. This means that these users are playing
on one of the queues, see \ref{sec:INFLobby.setStatus} INFLobby.setStatus for more
information about the users status.

\subsubsection{INFLobby.pollKeepAlive}
description: keep the current session alive\\
parameters: \verb"int sessionid"
\begin{description}
	\item[sessionid] the users sessionid
\end{description}
request:
\begin{verbatim}
<methodName>INFLobby.pollKeepAlive</methodName>
<params>
<param><value><int>1220084143</int></value></param>
</params>
\end{verbatim}
response:
\begin{verbatim}
<boolean>1</boolean>
\end{verbatim}
1 on success, 0 on failure


\input{fdl.tex}

\end{document}